## ELI5

**Problem.** Even when you ran a *scoped* push — say
`npm run push -- <env> assistants/foo.md` to update one assistant —
the engine rewrote the **entire** state file. Any pre-existing drift
in unrelated state entries (UUIDs from earlier sessions, untracked
local files, etc.) swept into the focused commit. Reviewers couldn't
tell from the state-file diff "what did this push actually change?"
and the state file became a pile of side effects accumulated across
sessions instead of a precise record of intent.

**What this fix does.** During a push, the engine tracks which
`resourceId`s it actually mutated (a per-section `Set<string>`). At
end-of-run, for **scoped pushes only**, it loads the on-disk state
fresh, replaces only the touched entries with the in-memory version,
and leaves everything else alone. Full pushes (no scope) still write
wholesale (existing behavior). Credentials are always replaced
because bootstrap pull populates them every push regardless.

This depends on Stack F's `ResourceState` because we need per-entry
metadata to distinguish "stale" from "just-not-touched."

**Outcome you'll notice.** A one-file `npm run push` produces a
one-file diff in the state file — same scope as the resource change.
Reviewers can read the state diff and tell "this push updated
assistant `foo`, here's its new hash" cleanly. Pre-existing drift
elsewhere in state stays where it is until you explicitly address it.

---

When push is scoped to specific paths, only update state entries for
the resources actually touched. A surgical push of two files used to
rewrite the entire state file, sweeping in pre-existing drift from
earlier pushes (improvements.md #15) and producing noisy diffs that
hide the actual scope of the change.

Files:
- src/state-merge.ts (NEW): mergeScoped(disk, inMemory, touched).
  For each section, replace only touched.X resourceIds with the in-memory
  version; leave the rest of disk's section as-is. Credentials are
  always replaced wholesale (bootstrap pull populates them on every
  push). Pure data, no I/O — safe to test directly.
- src/push.ts: TouchedSets tracker. Each upsertState call site
  records the resourceId. End-of-run, partial pushes call
  mergeScoped(loadState(), state, touched) before saveState; full
  pushes save wholesale (existing behavior).
- tests/state-merge.test.ts: replace-only-touched, leave-untouched,
  drift in untouched stays, credentials always replaced.

Closes improvements.md #15.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

## ELI5

**Problem.** Even when you ran a *scoped* push — say
`npm run push -- <env> assistants/foo.md` to update one assistant —
the engine rewrote the **entire** state file. Any pre-existing drift
in unrelated state entries (UUIDs from earlier sessions, untracked
local files, etc.) swept into the focused commit. Reviewers couldn't
tell from the state-file diff "what did this push actually change?"
and the state file became a pile of side effects accumulated across
sessions instead of a precise record of intent.

**What this fix does.** During a push, the engine tracks which
`resourceId`s it actually mutated (a per-section `Set<string>`). At
end-of-run, for **scoped pushes only**, it loads the on-disk state
fresh, replaces only the touched entries with the in-memory version,
and leaves everything else alone. Full pushes (no scope) still write
wholesale (existing behavior). Credentials are always replaced
because bootstrap pull populates them every push regardless.

This depends on Stack F's `ResourceState` because we need per-entry
metadata to distinguish "stale" from "just-not-touched."

**Outcome you'll notice.** A one-file `npm run push` produces a
one-file diff in the state file — same scope as the resource change.
Reviewers can read the state diff and tell "this push updated
assistant `foo`, here's its new hash" cleanly. Pre-existing drift
elsewhere in state stays where it is until you explicitly address it.

---

When push is scoped to specific paths, only update state entries for
the resources actually touched. A surgical push of two files used to
rewrite the entire state file, sweeping in pre-existing drift from
earlier pushes (improvements.md #15) and producing noisy diffs that
hide the actual scope of the change.

Files:
- src/state-merge.ts (NEW): mergeScoped(disk, inMemory, touched).
  For each section, replace only touched.X resourceIds with the in-memory
  version; leave the rest of disk's section as-is. Credentials are
  always replaced wholesale (bootstrap pull populates them on every
  push). Pure data, no I/O — safe to test directly.
- src/push.ts: TouchedSets tracker. Each upsertState call site
  records the resourceId. End-of-run, partial pushes call
  mergeScoped(loadState(), state, touched) before saveState; full
  pushes save wholesale (existing behavior).
- tests/state-merge.test.ts: replace-only-touched, leave-untouched,
  drift in untouched stays, credentials always replaced.

Closes improvements.md #15.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

## ELI5

**Problem.** Even when you ran a *scoped* push — say
`npm run push -- <env> assistants/foo.md` to update one assistant —
the engine rewrote the **entire** state file. Any pre-existing drift
in unrelated state entries (UUIDs from earlier sessions, untracked
local files, etc.) swept into the focused commit. Reviewers couldn't
tell from the state-file diff "what did this push actually change?"
and the state file became a pile of side effects accumulated across
sessions instead of a precise record of intent.

**What this fix does.** During a push, the engine tracks which
`resourceId`s it actually mutated (a per-section `Set<string>`). At
end-of-run, for **scoped pushes only**, it loads the on-disk state
fresh, replaces only the touched entries with the in-memory version,
and leaves everything else alone. Full pushes (no scope) still write
wholesale (existing behavior). Credentials are always replaced
because bootstrap pull populates them every push regardless.

This depends on Stack F's `ResourceState` because we need per-entry
metadata to distinguish "stale" from "just-not-touched."

**Outcome you'll notice.** A one-file `npm run push` produces a
one-file diff in the state file — same scope as the resource change.
Reviewers can read the state diff and tell "this push updated
assistant `foo`, here's its new hash" cleanly. Pre-existing drift
elsewhere in state stays where it is until you explicitly address it.

---

When push is scoped to specific paths, only update state entries for
the resources actually touched. A surgical push of two files used to
rewrite the entire state file, sweeping in pre-existing drift from
earlier pushes (improvements.md #15) and producing noisy diffs that
hide the actual scope of the change.

Files:
- src/state-merge.ts (NEW): mergeScoped(disk, inMemory, touched).
  For each section, replace only touched.X resourceIds with the in-memory
  version; leave the rest of disk's section as-is. Credentials are
  always replaced wholesale (bootstrap pull populates them on every
  push). Pure data, no I/O — safe to test directly.
- src/push.ts: TouchedSets tracker. Each upsertState call site
  records the resourceId. End-of-run, partial pushes call
  mergeScoped(loadState(), state, touched) before saveState; full
  pushes save wholesale (existing behavior).
- tests/state-merge.test.ts: replace-only-touched, leave-untouched,
  drift in untouched stays, credentials always replaced.

Closes improvements.md #15.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

## ELI5

**Problem.** Even when you ran a *scoped* push — say
`npm run push -- <env> assistants/foo.md` to update one assistant —
the engine rewrote the **entire** state file. Any pre-existing drift
in unrelated state entries (UUIDs from earlier sessions, untracked
local files, etc.) swept into the focused commit. Reviewers couldn't
tell from the state-file diff "what did this push actually change?"
and the state file became a pile of side effects accumulated across
sessions instead of a precise record of intent.

**What this fix does.** During a push, the engine tracks which
`resourceId`s it actually mutated (a per-section `Set<string>`). At
end-of-run, for **scoped pushes only**, it loads the on-disk state
fresh, replaces only the touched entries with the in-memory version,
and leaves everything else alone. Full pushes (no scope) still write
wholesale (existing behavior). Credentials are always replaced
because bootstrap pull populates them every push regardless.

This depends on Stack F's `ResourceState` because we need per-entry
metadata to distinguish "stale" from "just-not-touched."

**Outcome you'll notice.** A one-file `npm run push` produces a
one-file diff in the state file — same scope as the resource change.
Reviewers can read the state diff and tell "this push updated
assistant `foo`, here's its new hash" cleanly. Pre-existing drift
elsewhere in state stays where it is until you explicitly address it.

---

When push is scoped to specific paths, only update state entries for
the resources actually touched. A surgical push of two files used to
rewrite the entire state file, sweeping in pre-existing drift from
earlier pushes (improvements.md #15) and producing noisy diffs that
hide the actual scope of the change.

Files:
- src/state-merge.ts (NEW): mergeScoped(disk, inMemory, touched).
  For each section, replace only touched.X resourceIds with the in-memory
  version; leave the rest of disk's section as-is. Credentials are
  always replaced wholesale (bootstrap pull populates them on every
  push). Pure data, no I/O — safe to test directly.
- src/push.ts: TouchedSets tracker. Each upsertState call site
  records the resourceId. End-of-run, partial pushes call
  mergeScoped(loadState(), state, touched) before saveState; full
  pushes save wholesale (existing behavior).
- tests/state-merge.test.ts: replace-only-touched, leave-untouched,
  drift in untouched stays, credentials always replaced.

Closes improvements.md #15.

🤖 Generated with [Claude Code](https://claude.com/claude-code)